home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1999 January: Mac OS SDK / Dev.CD Jan 99 SDK1.toast / Development Kits / Interfaces&Libraries / Universal / Interfaces / CIncludes / QD3DRenderer.h < prev    next >
Encoding:
C/C++ Source or Header  |  1998-08-17  |  42.2 KB  |  1,268 lines  |  [TEXT/MPS ]
  1. /*
  2.      File:        QD3DRenderer.h
  3.  
  4.      Contains:    Q3Renderer types and routines                                          
  5.  
  6.      Version:    Technology:    Quickdraw 3D 1.5.4
  7.                  Release:    Universal Interfaces 3.2
  8.  
  9.      Copyright:    © 1995-1998 by Apple Computer, Inc., all rights reserved.
  10.  
  11.      Bugs?:        For bug reports, consult the following page on
  12.                  the World Wide Web:
  13.  
  14.                      http://developer.apple.com/bugreporter/
  15.  
  16. */
  17. #ifndef __QD3DRENDERER__
  18. #define __QD3DRENDERER__
  19.  
  20. #ifndef __QD3D__
  21. #include <QD3D.h>
  22. #endif
  23. #ifndef __QD3DSET__
  24. #include <QD3DSet.h>
  25. #endif
  26. #ifndef __QD3DVIEW__
  27. #include <QD3DView.h>
  28. #endif
  29.  
  30. #if TARGET_OS_MAC
  31. #ifndef __EVENTS__
  32. #include <Events.h>
  33. #endif
  34. #endif  /* TARGET_OS_MAC */
  35.  
  36.  
  37.  
  38. #if PRAGMA_ONCE
  39. #pragma once
  40. #endif
  41.  
  42. #ifdef __cplusplus
  43. extern "C" {
  44. #endif
  45.  
  46. #if PRAGMA_IMPORT
  47. #pragma import on
  48. #endif
  49.  
  50. #if PRAGMA_STRUCT_ALIGN
  51.     #pragma options align=power
  52. #elif PRAGMA_STRUCT_PACKPUSH
  53.     #pragma pack(push, 2)
  54. #elif PRAGMA_STRUCT_PACK
  55.     #pragma pack(2)
  56. #endif
  57.  
  58. #if PRAGMA_ENUM_ALWAYSINT
  59.     #pragma enumsalwaysint on
  60. #elif PRAGMA_ENUM_OPTIONS
  61.     #pragma option enum=int
  62. #elif PRAGMA_ENUM_PACK
  63.     #if __option(pack_enums)
  64.         #define PRAGMA_ENUM_PACK__QD3DRENDERER__
  65.     #endif
  66.     #pragma options(!pack_enums)
  67. #endif
  68.  
  69. /******************************************************************************
  70.  **                                                                             **
  71.  **                            User Interface Things                             **
  72.  **                                                                             **
  73.  *****************************************************************************/
  74. #if TARGET_OS_MAC
  75. /*
  76.  *  A callback to an application's event handling code. This is needed to    
  77.  *  support movable modal dialogs. The dialog's event filter calls this      
  78.  *  callback with events it does not handle.                                 
  79.  *  If an application handles the event it should return kQ3True.            
  80.  *  If the application does not handle the event it must return kQ3False and 
  81.  *  the dialog's event filter will pass the event to the system unhandled.   
  82.  */
  83. typedef CALLBACK_API_C( TQ3Boolean , TQ3MacOSDialogEventHandler )(const EventRecord *event);
  84.  
  85. struct TQ3DialogAnchor {
  86.     TQ3MacOSDialogEventHandler         clientEventHandler;
  87. };
  88. typedef struct TQ3DialogAnchor            TQ3DialogAnchor;
  89. #endif  /* TARGET_OS_MAC */
  90.  
  91. #if TARGET_OS_WIN32
  92.  
  93. struct TQ3DialogAnchor {
  94.     HWND                             ownerWindow;
  95. };
  96. typedef struct TQ3DialogAnchor            TQ3DialogAnchor;
  97. #endif  /* TARGET_OS_WIN32 */
  98.  
  99. #if TARGET_OS_UNIX
  100.  
  101. struct TQ3DialogAnchor {
  102.     void *                            notUsed;                    /* place holder */
  103. };
  104. typedef struct TQ3DialogAnchor            TQ3DialogAnchor;
  105. #endif  /* TARGET_OS_UNIX */
  106.  
  107. /******************************************************************************
  108.  **                                                                             **
  109.  **                            Renderer Functions                                 **
  110.  **                                                                             **
  111.  *****************************************************************************/
  112. EXTERN_API_C( TQ3RendererObject )
  113. Q3Renderer_NewFromType            (TQ3ObjectType             rendererObjectType);
  114.  
  115. EXTERN_API_C( TQ3ObjectType )
  116. Q3Renderer_GetType                (TQ3RendererObject         renderer);
  117.  
  118.  
  119. /* Q3Renderer_Flush has been replaced by Q3View_Flush */
  120. /* Q3Renderer_Sync has been replaced by Q3View_Sync */
  121.  
  122. /*
  123.  *    Q3Renderer_IsInteractive
  124.  *        Determine if this renderer is intended to be used interactively.
  125.  */
  126. EXTERN_API_C( TQ3Boolean )
  127. Q3Renderer_IsInteractive        (TQ3RendererObject         renderer);
  128.  
  129.  
  130. /*
  131.  *    Q3Renderer_HasModalConfigure
  132.  *        Determine if this renderer has a modal settings dialog.
  133.  *
  134.  *    Q3Renderer_ModalConfigure
  135.  *        Have the renderer pop up a modal dialog box to configure its settings.
  136.  *    dialogAnchor - is platform specific data passed by the client to support
  137.  *      movable modal dialogs. 
  138.  *    MacOS: this is a callback to the calling application's event handler.
  139.  *      The renderer calls this function with events not handled by the 
  140.  *      settings dialog. This is necessary in order to support movable modal 
  141.  *      dialogs. An application's event handler must return kQ3True if it 
  142.  *      handles the event passed to the callback or kQ3False if not. 
  143.  *      An application which doesn't want to support a movable modal configure
  144.  *      dialog should pass NULL for the clientEventHandler of TQ3DialogAnchor.
  145.  *    Win32: this is the HWND of the owning window (typically an application's
  146.  *      main window).
  147.  *  canceled - returns a boolean inditacating that the user canceled the 
  148.  *    dialog.
  149.  *      
  150.  */
  151. EXTERN_API_C( TQ3Boolean )
  152. Q3Renderer_HasModalConfigure    (TQ3RendererObject         renderer);
  153.  
  154. EXTERN_API_C( TQ3Status )
  155. Q3Renderer_ModalConfigure        (TQ3RendererObject         renderer,
  156.                                  TQ3DialogAnchor         dialogAnchor,
  157.                                  TQ3Boolean *            canceled);
  158.  
  159. /*
  160.  *    Q3RendererClass_GetNickNameString
  161.  *        Allows an application to get a renderers name string, the 
  162.  *        renderer is responsible for storing this in a localizable format
  163.  *        for example as a resource.  This string can then be used to provide
  164.  *        a selection mechanism for an application (for example in a menu).
  165.  *
  166.  *        If this call returns nil in the supplied string, then the App may 
  167.  *         choose to use the class name for the renderer.  You should always 
  168.  *        try to get the name string before using the class name, since the
  169.  *        class name is not localizable.
  170.  */
  171. EXTERN_API_C( TQ3Status )
  172. Q3RendererClass_GetNickNameString (TQ3ObjectType         rendererClassType,
  173.                                  TQ3ObjectClassNameString  rendererClassString);
  174.  
  175.  
  176. /*
  177.  *    Q3Renderer_GetConfigurationData
  178.  *        Allows an application to collect private renderer configuration data
  179.  *      which it will then save. For example in a preference file or in a 
  180.  *        style template. An application should tag this data with the 
  181.  *        Renderer's object  name.
  182.  *    
  183.  *        if dataBuffer is NULL actualDataSize returns the required size in 
  184.  *        bytes of a data buffer large enough to store private data. 
  185.  *
  186.  *      bufferSize is the actual size of the memory block pointed to by 
  187.  *        dataBuffer
  188.  *
  189.  *        actualDataSize - on return the actual number of bytes written to the 
  190.  *        buffer or if dataBuffer is NULL the required size of dataBuffer
  191.  * 
  192.  */
  193. EXTERN_API_C( TQ3Status )
  194. Q3Renderer_GetConfigurationData    (TQ3RendererObject         renderer,
  195.                                  unsigned char *        dataBuffer,
  196.                                  unsigned long             bufferSize,
  197.                                  unsigned long *        actualDataSize);
  198.  
  199. EXTERN_API_C( TQ3Status )
  200. Q3Renderer_SetConfigurationData    (TQ3RendererObject         renderer,
  201.                                  unsigned char *        dataBuffer,
  202.                                  unsigned long             bufferSize);
  203.  
  204.  
  205.  
  206. /******************************************************************************
  207.  **                                                                             **
  208.  **                        Interactive Renderer Specific Functions                 **
  209.  **                                                                             **
  210.  *****************************************************************************/
  211. /* CSG IDs attribute */
  212. #define kQ3AttributeTypeConstructiveSolidGeometryID        Q3_OBJECT_TYPE('c','s','g','i')
  213. /* Object IDs, to be applied as attributes on geometries */
  214. #define kQ3SolidGeometryObjNone (-1)
  215. #define kQ3SolidGeometryObjA     0
  216. #define kQ3SolidGeometryObjB     1
  217. #define kQ3SolidGeometryObjC     2
  218. #define kQ3SolidGeometryObjD     3
  219. #define kQ3SolidGeometryObjE     4
  220. /* Possible CSG equations */
  221.  
  222. enum TQ3CSGEquation {
  223.     kQ3CSGEquationAandB            = (long)0x88888888,
  224.     kQ3CSGEquationAandnotB        = 0x22222222,
  225.     kQ3CSGEquationAanBonCad        = 0x2F222F22,
  226.     kQ3CSGEquationnotAandB        = 0x44444444,
  227.     kQ3CSGEquationnAaBorCanB    = 0x74747474
  228. };
  229. typedef enum TQ3CSGEquation TQ3CSGEquation;
  230.  
  231. EXTERN_API_C( TQ3Status )
  232. Q3InteractiveRenderer_SetCSGEquation (TQ3RendererObject  renderer,
  233.                                  TQ3CSGEquation         equation);
  234.  
  235. EXTERN_API_C( TQ3Status )
  236. Q3InteractiveRenderer_GetCSGEquation (TQ3RendererObject  renderer,
  237.                                  TQ3CSGEquation *        equation);
  238.  
  239. EXTERN_API_C( TQ3Status )
  240. Q3InteractiveRenderer_SetPreferences (TQ3RendererObject  renderer,
  241.                                  long                     vendorID,
  242.                                  long                     engineID);
  243.  
  244. EXTERN_API_C( TQ3Status )
  245. Q3InteractiveRenderer_GetPreferences (TQ3RendererObject  renderer,
  246.                                  long *                    vendorID,
  247.                                  long *                    engineID);
  248.  
  249. EXTERN_API_C( TQ3Status )
  250. Q3InteractiveRenderer_SetDoubleBufferBypass (TQ3RendererObject  renderer,
  251.                                  TQ3Boolean             bypass);
  252.  
  253. EXTERN_API_C( TQ3Status )
  254. Q3InteractiveRenderer_GetDoubleBufferBypass (TQ3RendererObject  renderer,
  255.                                  TQ3Boolean *            bypass);
  256.  
  257. EXTERN_API_C( TQ3Status )
  258. Q3InteractiveRenderer_SetRAVEContextHints (TQ3RendererObject  renderer,
  259.                                  unsigned long             RAVEContextHints);
  260.  
  261. EXTERN_API_C( TQ3Status )
  262. Q3InteractiveRenderer_GetRAVEContextHints (TQ3RendererObject  renderer,
  263.                                  unsigned long *        RAVEContextHints);
  264.  
  265. EXTERN_API_C( TQ3Status )
  266. Q3InteractiveRenderer_SetRAVETextureFilter (TQ3RendererObject  renderer,
  267.                                  unsigned long             RAVEtextureFilterValue);
  268.  
  269. EXTERN_API_C( TQ3Status )
  270. Q3InteractiveRenderer_GetRAVETextureFilter (TQ3RendererObject  renderer,
  271.                                  unsigned long *        RAVEtextureFilterValue);
  272.  
  273.  
  274. /******************************************************************************
  275.  **                                                                             **
  276.  **                            Renderer View Tools                                 **
  277.  **                                                                             **
  278.  **                    You may only call these methods from a plug-in             **
  279.  **                                                                             **
  280.  *****************************************************************************/
  281. /*
  282.  *    Call by a renderer to call the user "idle" method, with progress 
  283.  *    information.
  284.  *    
  285.  *    Pass in (view, 0, n) on first call
  286.  *    Pass in (view, 1..n-1, n) during rendering
  287.  *    Pass in (view, n, n) upon completion
  288.  *    
  289.  *    Note: The user must have supplied an idleProgress method with 
  290.  *    Q3XView_SetIdleProgressMethod. Otherwise, the generic idle method is
  291.  *    called with no progress data. e.g. the Q3View_SetIdleMethod method
  292.  *    is called instead. (current and final are ignored, essentially.)
  293.  *
  294.  *    Returns kQ3Failure if rendering is cancelled.
  295.  */
  296. EXTERN_API_C( TQ3Status )
  297. Q3XView_IdleProgress            (TQ3ViewObject             view,
  298.                                  unsigned long             current,
  299.                                  unsigned long             completed);
  300.  
  301. /*
  302.  *    Called by an asynchronous renderer when it completes a frame.
  303.  */
  304. EXTERN_API_C( TQ3Status )
  305. Q3XView_EndFrame                (TQ3ViewObject             view);
  306.  
  307.  
  308. /******************************************************************************
  309.  **                                                                             **
  310.  **                            Renderer AttributeSet Tools                         **
  311.  **                                                                             **
  312.  **                    You may only call these methods from a plug-in             **
  313.  **                                                                             **
  314.  *****************************************************************************/
  315. /*
  316.  *    Faster access to geometry attribute sets.
  317.  *    
  318.  *    Returns pointer to INTERNAL data structure for elements and attributes
  319.  *    in an attributeSet, or NULL if no attribute exists.
  320.  *    
  321.  *    For attributes of type kQ3AttributeType..., the internal data structure
  322.  *    is identical to the data structure used in Q3AttributeSet_Add.
  323.  */
  324. EXTERN_API_C( void *)
  325. Q3XAttributeSet_GetPointer        (TQ3AttributeSet         attributeSet,
  326.                                  TQ3AttributeType         attributeType);
  327.  
  328.  
  329.  
  330. enum {
  331.     kQ3XAttributeMaskNone        = 0L,
  332.     kQ3XAttributeMaskSurfaceUV    = 1 << (kQ3AttributeTypeSurfaceUV - 1),
  333.     kQ3XAttributeMaskShadingUV    = 1 << (kQ3AttributeTypeShadingUV - 1),
  334.     kQ3XAttributeMaskNormal        = 1 << (kQ3AttributeTypeNormal - 1),
  335.     kQ3XAttributeMaskAmbientCoefficient = 1 << (kQ3AttributeTypeAmbientCoefficient - 1),
  336.     kQ3XAttributeMaskDiffuseColor = 1 << (kQ3AttributeTypeDiffuseColor - 1),
  337.     kQ3XAttributeMaskSpecularColor = 1 << (kQ3AttributeTypeSpecularColor - 1),
  338.     kQ3XAttributeMaskSpecularControl = 1 << (kQ3AttributeTypeSpecularControl - 1),
  339.     kQ3XAttributeMaskTransparencyColor = 1 << (kQ3AttributeTypeTransparencyColor - 1),
  340.     kQ3XAttributeMaskSurfaceTangent = 1 << (kQ3AttributeTypeSurfaceTangent - 1),
  341.     kQ3XAttributeMaskHighlightState = 1 << (kQ3AttributeTypeHighlightState - 1),
  342.     kQ3XAttributeMaskSurfaceShader = 1 << (kQ3AttributeTypeSurfaceShader - 1),
  343.     kQ3XAttributeMaskCustomAttribute = (long)0x80000000,
  344.     kQ3XAttributeMaskAll        = (long)0x800007FF,
  345.     kQ3XAttributeMaskInherited    = 0x03FF,
  346.     kQ3XAttributeMaskInterpolated = kQ3XAttributeMaskSurfaceUV | kQ3XAttributeMaskShadingUV | kQ3XAttributeMaskNormal | kQ3XAttributeMaskAmbientCoefficient | kQ3XAttributeMaskDiffuseColor | kQ3XAttributeMaskSpecularColor | kQ3XAttributeMaskSpecularControl | kQ3XAttributeMaskTransparencyColor | kQ3XAttributeMaskSurfaceTangent
  347. };
  348.  
  349.  
  350. typedef unsigned long                     TQ3XAttributeMask;
  351. EXTERN_API_C( TQ3XAttributeMask )
  352. Q3XAttributeSet_GetMask            (TQ3AttributeSet         attributeSet);
  353.  
  354.  
  355. /******************************************************************************
  356.  **                                                                             **
  357.  **                            Renderer Draw Context Tools                         **
  358.  **                                                                             **
  359.  *****************************************************************************/
  360. typedef struct OpaqueTQ3XDrawRegion*     TQ3XDrawRegion;
  361. EXTERN_API_C( TQ3Status )
  362. Q3XDrawContext_GetDrawRegion    (TQ3DrawContextObject     drawContext,
  363.                                  TQ3XDrawRegion *        drawRegion);
  364.  
  365.  
  366. enum TQ3XDrawContextValidationMasks {
  367.     kQ3XDrawContextValidationClearFlags = 0x00000000,
  368.     kQ3XDrawContextValidationDoubleBuffer = 1 << 0,
  369.     kQ3XDrawContextValidationShader = 1 << 1,
  370.     kQ3XDrawContextValidationClearFunction = 1 << 2,
  371.     kQ3XDrawContextValidationActiveBuffer = 1 << 3,
  372.     kQ3XDrawContextValidationInternalOffScreen = 1 << 4,
  373.     kQ3XDrawContextValidationPane = 1 << 5,
  374.     kQ3XDrawContextValidationMask = 1 << 6,
  375.     kQ3XDrawContextValidationDevice = 1 << 7,
  376.     kQ3XDrawContextValidationWindow = 1 << 8,
  377.     kQ3XDrawContextValidationWindowSize = 1 << 9,
  378.     kQ3XDrawContextValidationWindowClip = 1 << 10,
  379.     kQ3XDrawContextValidationWindowPosition = 1 << 11,
  380.     kQ3XDrawContextValidationPlatformAttributes = 1 << 12,
  381.     kQ3XDrawContextValidationForegroundShader = 1 << 13,
  382.     kQ3XDrawContextValidationBackgroundShader = 1 << 14,
  383.     kQ3XDrawContextValidationColorPalette = 1 << 15,
  384.     kQ3XDrawContextValidationAll = (long)0xFFFFFFFF
  385. };
  386. typedef enum TQ3XDrawContextValidationMasks TQ3XDrawContextValidationMasks;
  387.  
  388. typedef unsigned long                     TQ3XDrawContextValidation;
  389. EXTERN_API_C( TQ3Status )
  390. Q3XDrawContext_ClearValidationFlags (TQ3DrawContextObject  drawContext);
  391.  
  392. EXTERN_API_C( TQ3Status )
  393. Q3XDrawContext_GetValidationFlags (TQ3DrawContextObject  drawContext,
  394.                                  TQ3XDrawContextValidation * validationFlags);
  395.  
  396.  
  397. /******************************************************************************
  398.  **                                                                             **
  399.  **                            Renderer Draw Region Tools                         **
  400.  **                                                                             **
  401.  *****************************************************************************/
  402.  
  403. enum TQ3XDevicePixelType {
  404.                                                                 /* These do not indicate byte ordering   */
  405.     kQ3XDevicePixelTypeInvalid    = 0,                            /* Unknown, un-initialized type     */
  406.     kQ3XDevicePixelTypeRGB32    = 1,                            /* Alpha:8 (ignored), R:8, G:8, B:8 */
  407.     kQ3XDevicePixelTypeARGB32    = 2,                            /* Alpha:8, R:8, G:8, B:8              */
  408.     kQ3XDevicePixelTypeRGB24    = 3,                            /* 24 bits/pixel, R:8, G:8, B:8     */
  409.     kQ3XDevicePixelTypeRGB16    = 4,                            /* Alpha:1 (ignored), R:5, G:5, B:5 */
  410.     kQ3XDevicePixelTypeARGB16    = 5,                            /* Alpha:1, R:5, G:5, B:5              */
  411.     kQ3XDevicePixelTypeRGB16_565 = 6,                            /* 16 bits/pixel, R:5, G:6, B:5     */
  412.     kQ3XDevicePixelTypeIndexed8    = 7,                            /* 8-bit color table index             */
  413.     kQ3XDevicePixelTypeIndexed4    = 8,                            /* 4-bit color table index             */
  414.     kQ3XDevicePixelTypeIndexed2    = 9,                            /* 2-bit color table index             */
  415.     kQ3XDevicePixelTypeIndexed1    = 10                            /* 1-bit color table index             */
  416. };
  417. typedef enum TQ3XDevicePixelType TQ3XDevicePixelType;
  418.  
  419.  
  420. enum TQ3XClipMaskState {
  421.     kQ3XClipMaskFullyExposed    = 0,
  422.     kQ3XClipMaskPartiallyExposed = 1,
  423.     kQ3XClipMaskNotExposed        = 2
  424. };
  425. typedef enum TQ3XClipMaskState TQ3XClipMaskState;
  426.  
  427.  
  428. struct TQ3XColorDescriptor {
  429.     unsigned long                     redShift;
  430.     unsigned long                     redMask;
  431.     unsigned long                     greenShift;
  432.     unsigned long                     greenMask;
  433.     unsigned long                     blueShift;
  434.     unsigned long                     blueMask;
  435.     unsigned long                     alphaShift;
  436.     unsigned long                     alphaMask;
  437. };
  438. typedef struct TQ3XColorDescriptor        TQ3XColorDescriptor;
  439.  
  440. struct TQ3XDrawRegionDescriptor {
  441.     unsigned long                     width;
  442.     unsigned long                     height;
  443.     unsigned long                     rowBytes;
  444.     unsigned long                     pixelSize;
  445.     TQ3XDevicePixelType             pixelType;
  446.     TQ3XColorDescriptor             colorDescriptor;
  447.     TQ3Endian                         bitOrder;
  448.     TQ3Endian                         byteOrder;
  449.     TQ3Bitmap *                        clipMask;
  450. };
  451. typedef struct TQ3XDrawRegionDescriptor    TQ3XDrawRegionDescriptor;
  452.  
  453. enum TQ3XDrawRegionServicesMasks {
  454.     kQ3XDrawRegionServicesNoneFlag = 0L,
  455.     kQ3XDrawRegionServicesClearFlag = 1 << 0,
  456.     kQ3XDrawRegionServicesDontLockDDSurfaceFlag = 1 << 1
  457. };
  458. typedef enum TQ3XDrawRegionServicesMasks TQ3XDrawRegionServicesMasks;
  459.  
  460.  
  461. typedef unsigned long                     TQ3XDrawRegionServices;
  462. typedef CALLBACK_API_C( void , TQ3XDrawRegionRendererPrivateDeleteMethod )(void *rendererPrivate);
  463. EXTERN_API_C( TQ3Status )
  464. Q3XDrawRegion_GetDeviceScaleX    (TQ3XDrawRegion         drawRegion,
  465.                                  float *                deviceScaleX);
  466.  
  467. EXTERN_API_C( TQ3Status )
  468. Q3XDrawRegion_GetDeviceScaleY    (TQ3XDrawRegion         drawRegion,
  469.                                  float *                deviceScaleY);
  470.  
  471.  
  472. EXTERN_API_C( TQ3Status )
  473. Q3XDrawRegion_GetDeviceOffsetX    (TQ3XDrawRegion         drawRegion,
  474.                                  float *                deviceOffsetX);
  475.  
  476. EXTERN_API_C( TQ3Status )
  477. Q3XDrawRegion_GetDeviceOffsetY    (TQ3XDrawRegion         drawRegion,
  478.                                  float *                deviceOffsetX);
  479.  
  480.  
  481. EXTERN_API_C( TQ3Status )
  482. Q3XDrawRegion_GetWindowScaleX    (TQ3XDrawRegion         drawRegion,
  483.                                  float *                windowScaleX);
  484.  
  485. EXTERN_API_C( TQ3Status )
  486. Q3XDrawRegion_GetWindowScaleY    (TQ3XDrawRegion         drawRegion,
  487.                                  float *                windowScaleY);
  488.  
  489.  
  490. EXTERN_API_C( TQ3Status )
  491. Q3XDrawRegion_GetWindowOffsetX    (TQ3XDrawRegion         drawRegion,
  492.                                  float *                windowOffsetX);
  493.  
  494. EXTERN_API_C( TQ3Status )
  495. Q3XDrawRegion_GetWindowOffsetY    (TQ3XDrawRegion         drawRegion,
  496.                                  float *                windowOffsetY);
  497.  
  498. EXTERN_API_C( TQ3Status )
  499. Q3XDrawRegion_IsActive            (TQ3XDrawRegion         drawRegion,
  500.                                  TQ3Boolean *            isActive);
  501.  
  502.  
  503. EXTERN_API_C( TQ3Status )
  504. Q3XDrawRegion_GetNextRegion        (TQ3XDrawRegion         drawRegion,
  505.                                  TQ3XDrawRegion *        nextDrawRegion);
  506.  
  507. /* 
  508.  *  One of the next two functions must be called before using a draw region 
  509.  */
  510. /*
  511.  *    Use this Start function if double buffering/image access services from the
  512.  *    Draw Context are not needed, you may still request clear for example
  513.  */
  514. EXTERN_API_C( TQ3Status )
  515. Q3XDrawRegion_Start                (TQ3XDrawRegion         drawRegion,
  516.                                  TQ3XDrawRegionServices  services,
  517.                                  TQ3XDrawRegionDescriptor ** descriptor);
  518.  
  519. /*
  520.  *    Use this Start function if double buffering or image access services from 
  521.  *  the Draw Context are needed.
  522.  */
  523. EXTERN_API_C( TQ3Status )
  524. Q3XDrawRegion_StartAccessToImageBuffer (TQ3XDrawRegion     drawRegion,
  525.                                  TQ3XDrawRegionServices  services,
  526.                                  TQ3XDrawRegionDescriptor ** descriptor,
  527.                                  void **                image);
  528.  
  529. /*
  530.  *    This function is used to indicate that access to a DrawRegion is ended.
  531.  */
  532. EXTERN_API_C( TQ3Status )
  533. Q3XDrawRegion_End                (TQ3XDrawRegion         drawRegion);
  534.  
  535. EXTERN_API_C( TQ3Status )
  536. Q3XDrawRegion_GetDeviceTransform (TQ3XDrawRegion         drawRegion,
  537.                                  TQ3Matrix4x4 **        deviceTransform);
  538.  
  539. EXTERN_API_C( TQ3Status )
  540. Q3XDrawRegion_GetClipFlags        (TQ3XDrawRegion         drawRegion,
  541.                                  TQ3XClipMaskState *    clipMaskState);
  542.  
  543. EXTERN_API_C( TQ3Status )
  544. Q3XDrawRegion_GetClipMask        (TQ3XDrawRegion         drawRegion,
  545.                                  TQ3Bitmap **            clipMask);
  546.  
  547. #if TARGET_OS_MAC
  548. EXTERN_API_C( TQ3Status )
  549. Q3XDrawRegion_GetClipRegion        (TQ3XDrawRegion         drawRegion,
  550.                                  RgnHandle *            rgnHandle);
  551.  
  552. EXTERN_API_C( TQ3Status )
  553. Q3XDrawRegion_GetGDHandle        (TQ3XDrawRegion         drawRegion,
  554.                                  GDHandle *                gdHandle);
  555.  
  556. #endif  /* TARGET_OS_MAC */
  557.  
  558. EXTERN_API_C( TQ3Status )
  559. Q3XDrawRegion_GetRendererPrivate (TQ3XDrawRegion         drawRegion,
  560.                                  void **                rendererPrivate);
  561.  
  562. EXTERN_API_C( TQ3Status )
  563. Q3XDrawRegion_SetRendererPrivate (TQ3XDrawRegion         drawRegion,
  564.                                  const void *            rendererPrivate,
  565.                                  TQ3XDrawRegionRendererPrivateDeleteMethod  deleteMethod);
  566.  
  567. EXTERN_API_C( TQ3Status )
  568. Q3XDrawRegion_SetUseDefaultRendererFlag (TQ3XDrawRegion  drawRegion,
  569.                                  TQ3Boolean             flag);
  570.  
  571. EXTERN_API_C( TQ3Status )
  572. Q3XDrawRegion_GetUseDefaultRendererFlag (TQ3XDrawRegion  drawRegion,
  573.                                  TQ3Boolean *            useDefaultRenderingFlag);
  574.  
  575.  
  576.  
  577. /******************************************************************************
  578.  **                                                                             **
  579.  **                            Renderer Class Methods                             **
  580.  **                                                                             **
  581.  *****************************************************************************/
  582. /*
  583.  *    Methods from Object
  584.  *        kQ3XMethodTypeObjectClassRegister
  585.  *        kQ3XMethodTypeObjectClassUnregister
  586.  *        kQ3XMethodTypeObjectNew
  587.  *        kQ3XMethodTypeObjectDelete
  588.  *        kQ3XMethodTypeObjectRead
  589.  *        kQ3XMethodTypeObjectTraverse
  590.  *        kQ3XMethodTypeObjectWrite
  591.  *        
  592.  *    Methods from Shared
  593.  *        kQ3MethodTypeSharedEdited
  594.  *
  595.  *    Renderer Methods
  596.  *    
  597.  *    The renderer methods should be implemented according to the type
  598.  *    of renderer being written.
  599.  *
  600.  *    For the purposes of documentation, there are two basic types of
  601.  *    renderers: 
  602.  *
  603.  *        Interactive
  604.  *            Interactive Renderer
  605.  *            WireFrame Renderer
  606.  *        
  607.  *        Deferred
  608.  *            a ray-tracer
  609.  *            painter's algorithm renderer (cached in a BSP triangle tree)
  610.  *            an artistic renderer (simulates a pencil drawing, etc.)
  611.  *
  612.  *    The main difference is how each renderer handles incoming state and 
  613.  *    geometry.
  614.  *
  615.  *    An interactive renderer immediately transforms, culls, and shades
  616.  *    incoming geometry and performs rasterization. For example, in a 
  617.  *    single-buffered WireFrame renderer, you will see a new triangle
  618.  *    immediately after Q3Triangle_Draw (if it's visible, of course).
  619.  *
  620.  *    A deferred renderer caches the view state and each geometry, 
  621.  *    converting into any internal queue of drawing commands. Rasterization
  622.  *    is not actually performed until all data has been submitted.
  623.  *    
  624.  *    For example, a ray-tracer may not rasterize anything until the
  625.  *    end of the rendering loop, or until an EndFrame call is made.
  626.  */
  627.  
  628. /******************************************************************************
  629.  **                                                                             **
  630.  **                        Renderer User Interface Methods                         **
  631.  **                                                                             **
  632.  *****************************************************************************/
  633. /*
  634.  *    kQ3XMethodTypeRendererIsInteractive
  635.  *    
  636.  *    There is no actual method with this - the metahandler simply returns
  637.  *  "(TQ3XFunctionPointer)kQ3True" for this "method" if the renderer is 
  638.  *  intended to be used in interactive settings, and   
  639.  *    "(TQ3XFunctionPointer)kQ3False" otherwise. 
  640.  *  
  641.  *  If neither value is specified in the metahandler, the renderer 
  642.  *  is *assumed to be non-interactive*!!!
  643.  *    
  644.  *    OPTIONAL
  645.  */
  646.  
  647. enum {
  648.     kQ3XMethodTypeRendererIsInteractive = FOUR_CHAR_CODE('isin')
  649. };
  650.  
  651.  
  652. /*
  653.  *    TQ3XRendererModalConfigureMethod
  654.  *    
  655.  *    This method should pop up a modal dialog to edit the renderer settings 
  656.  *    found in the renderer private. 
  657.  *    
  658.  *    dialogAnchor - is platform specific data passed by the client to support
  659.  *      movable modal dialogs. 
  660.  *    MacOS: this is a callback to the calling application's event handler.
  661.  *      The renderer calls this function with events not handled by the 
  662.  *      settings dialog. This is necessary in order to support movable modal 
  663.  *      dialogs. An application's event handler must return kQ3True if it 
  664.  *      handles the event passed to the callback or kQ3False if not. 
  665.  *      An application which doesn't want to support a movable modal configure
  666.  *      dialog should pass NULL for the clientEventHandler of TQ3DialogAnchor.
  667.  *      A renderer should implement a non-movable style dialog in that case.
  668.  *    Win32: this is the HWND of the owning window (typically an application's
  669.  *      main window).  (Win32 application modal dialogs are always movable.)
  670.  *  canceled - returns a boolean inditacating that the user canceled the 
  671.  *    dialog.
  672.  *    
  673.  *    OPTIONAL
  674.  */
  675.  
  676. enum {
  677.     kQ3XMethodTypeRendererModalConfigure = FOUR_CHAR_CODE('rdmc')
  678. };
  679.  
  680. typedef CALLBACK_API_C( TQ3Status , TQ3XRendererModalConfigureMethod )(TQ3RendererObject renderer, TQ3DialogAnchor dialogAnchor, TQ3Boolean *canceled, void *rendererPrivate);
  681. /*
  682.  *    kQ3XMethodTypeRendererGetNickNameString
  683.  *    
  684.  *        Allows an application to collect the name of the renderer for
  685.  *        display in a user interface item such as a menu.
  686.  *    
  687.  *        If dataBuffer is NULL actualDataSize returns the required size in 
  688.  *        bytes of a data buffer large enough to store the renderer name. 
  689.  *
  690.  *      bufferSize is the actual size of the memory block pointed to by 
  691.  *        dataBuffer
  692.  *
  693.  *        actualDataSize - on return the actual number of bytes written to the
  694.  *        buffer or if dataBuffer is NULL the required size of dataBuffer
  695.  *
  696.  *    OPTIONAL
  697.  */
  698.  
  699. enum {
  700.     kQ3XMethodTypeRendererGetNickNameString = FOUR_CHAR_CODE('rdns')
  701. };
  702.  
  703. typedef CALLBACK_API_C( TQ3Status , TQ3XRendererGetNickNameStringMethod )(unsigned char *dataBuffer, unsigned long bufferSize, unsigned long *actualDataSize);
  704. /*
  705.  *    kQ3XMethodTypeRendererGetConfigurationData
  706.  *    
  707.  *        Allows an application to collect private configuration data from the
  708.  *      renderer which it will then save. For example in a preference file, 
  709.  *      a registry key (on Windows) or in a style template. An application 
  710.  *      should tag this data with the renderer's object name.
  711.  *    
  712.  *        If dataBuffer is NULL actualDataSize returns the required size in 
  713.  *        bytes of a data buffer large enough to store private data. 
  714.  *
  715.  *      bufferSize is the actual size of the memory block pointed to by 
  716.  *        dataBuffer
  717.  *
  718.  *        actualDataSize - on return the actual number of bytes written to the
  719.  *        buffer or if dataBuffer is NULL the required size of dataBuffer
  720.  *
  721.  *    OPTIONAL
  722.  */
  723.  
  724. enum {
  725.     kQ3XMethodTypeRendererGetConfigurationData = FOUR_CHAR_CODE('rdgp')
  726. };
  727.  
  728. typedef CALLBACK_API_C( TQ3Status , TQ3XRendererGetConfigurationDataMethod )(TQ3RendererObject renderer, unsigned char *dataBuffer, unsigned long bufferSize, unsigned long *actualDataSize, void *rendererPrivate);
  729. /*
  730.  *    TQ3XRendererSetConfigurationDataMethod
  731.  *    
  732.  *        Allows an application to pass private configuration data which has
  733.  *         previously  been obtained from a renderer via 
  734.  *        Q3Renderer_GetConfigurationData. For example in a preference file or 
  735.  *        in a style template. An application should tag this data with the 
  736.  *        renderer's object name.
  737.  *    
  738.  *      bufferSize is the actual size of the memory block pointed to by 
  739.  *        dataBuffer
  740.  *
  741.  *    OPTIONAL
  742.  */
  743.  
  744. enum {
  745.     kQ3XMethodTypeRendererSetConfigurationData = FOUR_CHAR_CODE('rdsp')
  746. };
  747.  
  748. typedef CALLBACK_API_C( TQ3Status , TQ3XRendererSetConfigurationDataMethod )(TQ3RendererObject renderer, unsigned char *dataBuffer, unsigned long bufferSize, void *rendererPrivate);
  749. /******************************************************************************
  750.  **                                                                             **
  751.  **                        Renderer Drawing State Methods                         **
  752.  **                                                                             **
  753.  *****************************************************************************/
  754. /*
  755.  *    TQ3RendererStartFrame
  756.  *    
  757.  *    The StartFrame method is called first at Q3View_StartRendering
  758.  *    and should:
  759.  *        - initialize any renderer state to defaults
  760.  *        - extract any and all useful data from the drawContext
  761.  *
  762.  *    If your renderer passed in kQ3RendererFlagClearBuffer at 
  763.  *    registration, then it should also:
  764.  *        - clear the drawContext 
  765.  *    
  766.  *        When clearing, your renderer may opt to:
  767.  *        - NOT clear anything (if you touch every pixel, for example)
  768.  *        - to clear with your own routine, or
  769.  *        - to use the draw context default clear method by calling 
  770.  *        Q3DrawContext_Clear. Q3DrawContext_Clear takes advantage of
  771.  *        any available hardware in the system for clearing.
  772.  *    
  773.  *    This call also signals the start of all default submit commands from
  774.  *    the view. The renderer will receive updates for the default view
  775.  *    state via its Update methods before StartPass is called.
  776.  *    
  777.  *    REQUIRED
  778.  */
  779.  
  780. enum {
  781.     kQ3XMethodTypeRendererStartFrame = FOUR_CHAR_CODE('rdcl')
  782. };
  783.  
  784. typedef CALLBACK_API_C( TQ3Status , TQ3XRendererStartFrameMethod )(TQ3ViewObject view, void *rendererPrivate, TQ3DrawContextObject drawContext);
  785. /*
  786.  *    kQ3XMethodTypeRendererStartPass
  787.  *    TQ3XRendererStartPassMethod
  788.  *    
  789.  *    The StartPass method is called during Q3View_StartRendering but after
  790.  *    the StartFrame command. It should:
  791.  *        - collect camera and light information
  792.  *    
  793.  *    If your renderer supports deferred camera transformation, camera is the
  794.  *    main camera which will be submitted in the hierarchy somewhere. It
  795.  *    is never NULL.
  796.  *
  797.  *    If your renderer does not support deferred camera transformation, camera
  798.  *    is the transformed camera.
  799.  *
  800.  *    If your renderer supports deferred light transformation, lights will be
  801.  *    NULL, and will be submitted to your light draw methods instead.
  802.  *
  803.  *    This call signals the end of the default update state, and the start of 
  804.  *  submit commands from the user to the view.
  805.  *
  806.  *    REQUIRED
  807.  */
  808.  
  809. enum {
  810.     kQ3XMethodTypeRendererStartPass = FOUR_CHAR_CODE('rdst')
  811. };
  812.  
  813. typedef CALLBACK_API_C( TQ3Status , TQ3XRendererStartPassMethod )(TQ3ViewObject view, void *rendererPrivate, TQ3CameraObject camera, TQ3GroupObject lightGroup);
  814. /*
  815.  *    kQ3XMethodTypeRendererFlushFrame
  816.  *    TQ3XRendererFlushFrameMethod
  817.  *    
  818.  *    This call is only implemented by asynchronous renderers.
  819.  *    
  820.  *    The FlushFrame method is called between the StartPass and EndPass
  821.  *    methods and is called when the user wishes to flush any asynchronous
  822.  *    drawing tasks (which draw to the drawcontext), but does not want 
  823.  *    to block.
  824.  *    
  825.  *    The result of this call is that an image should "eventually" appear
  826.  *    asynchronously.
  827.  *    
  828.  *    For asynchronous rendering, this call is non-blocking.
  829.  *    
  830.  *    An interactive renderer should ensure that all received
  831.  *    geometries are drawn in the image.
  832.  *    
  833.  *    An interactive renderer that talks to hardware should force
  834.  *    the hardware to generate an image.
  835.  *    
  836.  *    A deferred renderer should exhibit a similar behaviour,
  837.  *    though it is not required.  A deferred renderer should spawn
  838.  *    a process that generates a partial image from the currently
  839.  *    accumulated drawing state. 
  840.  *    
  841.  *    However, for renderers such as ray-tracers which generally are
  842.  *    quite compute-intensive, FlushFrame is not required and is a no-op.
  843.  *
  844.  *    OPTIONAL
  845.  */
  846.  
  847. enum {
  848.     kQ3XMethodTypeRendererFlushFrame = FOUR_CHAR_CODE('rdfl')
  849. };
  850.  
  851. typedef CALLBACK_API_C( TQ3Status , TQ3XRendererFlushFrameMethod )(TQ3ViewObject view, void *rendererPrivate, TQ3DrawContextObject drawContext);
  852. /*
  853.  *    kQ3XMethodTypeRendererEndPass
  854.  *    TQ3XRendererEndPassMethod
  855.  *    
  856.  *    The EndPass method is called at Q3View_EndRendering and signals
  857.  *    the end of submit commands to the view.
  858.  *
  859.  *    If an error occurs, the renderer should call Q3XError_Post and
  860.  *    return kQ3ViewStatusError.
  861.  *    
  862.  *    If a renderer requires another pass on the renderering data,
  863.  *    it should return kQ3ViewStatusRetraverse.
  864.  *    
  865.  *    If rendering was cancelled, this function will not be called
  866.  *    and the view will handle returning kQ3ViewStatusCancelled;
  867.  *    
  868.  *    Otherwise, your renderer should begin completing the process of 
  869.  *    generating the image in the drawcontext. If you have buffered
  870.  *    any drawing data, flush it. RendererEnd should have a similar
  871.  *    effect as RendererFlushFrame.
  872.  *    
  873.  *    If the renderer is synchronous:
  874.  *        - complete rendering of the entire frame
  875.  *        if the renderer supports kQ3RendererClassSupportDoubleBuffer
  876.  *            - Update the front buffer
  877.  *        else
  878.  *            - DrawContext will update the front buffer after returning
  879.  *
  880.  *    If the renderer is asynchronous
  881.  *        - spawn rendering thread for entire frame
  882.  *        if the renderer supports kQ3RendererClassSupportDoubleBuffer,
  883.  *            - you must eventually update the front buffer asynchronously
  884.  *        else
  885.  *            - you must eventually update the back buffer asynchronously
  886.  *            
  887.  *    REQUIRED
  888.  */
  889.  
  890. enum {
  891.     kQ3XMethodTypeRendererEndPass = FOUR_CHAR_CODE('rded')
  892. };
  893.  
  894. typedef CALLBACK_API_C( TQ3ViewStatus , TQ3XRendererEndPassMethod )(TQ3ViewObject view, void *rendererPrivate);
  895. /*
  896.  *    kQ3XMethodTypeRendererEndFrame
  897.  *    TQ3XRendererEndFrame
  898.  *    
  899.  *    This call is only implemented by asynchronous renderers.
  900.  *
  901.  *    The EndFrame method is called from Q3View_Sync, which is
  902.  *    called after Q3View_EndRendering and signals that the user
  903.  *    wishes to see the completed image and is willing to block.
  904.  *    
  905.  *    If your renderer supports kQ3RendererFlagDoubleBuffer
  906.  *        - update the front buffer completely 
  907.  *    else
  908.  *        - update the back buffer completely
  909.  *
  910.  *    This call is equivalent in functionality to RendererFlushFrame
  911.  *    but blocks until the image is completed.
  912.  *    
  913.  *    If no method is supplied, the default is a no-op.
  914.  *    
  915.  *    NOTE: Registering a method of this type indicates that your renderer will
  916.  *    be rendering after Q3View_EndRendering has been called.
  917.  *    
  918.  *    OPTIONAL
  919.  */
  920.  
  921. enum {
  922.     kQ3XMethodTypeRendererEndFrame = FOUR_CHAR_CODE('rdsy')
  923. };
  924.  
  925. typedef CALLBACK_API_C( TQ3Status , TQ3XRendererEndFrameMethod )(TQ3ViewObject view, void *rendererPrivate, TQ3DrawContextObject drawContext);
  926. /*
  927.  *    The RendererCancel method is called after Q3View_StartRendering
  928.  *    and signals the termination of all rendering operations.
  929.  *
  930.  *    A renderer should clean up any cached data, and cancel all 
  931.  *    rendering operations.
  932.  *    
  933.  *    If called before Q3View_EndRendering, the RendererEnd method
  934.  *    is NOT called.
  935.  *    
  936.  *    If called after Q3View_EndRendering, the renderer should kill
  937.  *    any threads and terminate any further rendering.
  938.  *    
  939.  *    REQUIRED
  940.  */
  941.  
  942. enum {
  943.     kQ3XMethodTypeRendererCancel = FOUR_CHAR_CODE('rdab')
  944. };
  945.  
  946. typedef CALLBACK_API_C( void , TQ3XRendererCancelMethod )(TQ3ViewObject view, void *rendererPrivate);
  947. /******************************************************************************
  948.  **                                                                             **
  949.  **                        Renderer DrawContext Methods                         **
  950.  **                                                                             **
  951.  *****************************************************************************/
  952. /*
  953.  *    kQ3XMethodTypeRendererPush
  954.  *    TQ3XRendererPushMethod
  955.  *    
  956.  *    kQ3XMethodTypeRendererPop
  957.  *    TQ3XRendererPopMethod
  958.  *    
  959.  *    These methods are called whenever the graphics state in the view
  960.  *    is pushed or popped. The user may isolate state by calling:
  961.  *    
  962.  *    Q3Attribute_Submit(kQ3AttributeTypeDiffuseColor, &red, view);
  963.  *    Q3Attribute_Submit(kQ3AttributeTypeTransparencyColor, &blue, view);
  964.  *    Q3Attribute_Submit(kQ3AttributeTypeSpecularColor, &white, view);
  965.  *    Q3Box_Submit(&unitBox, view);
  966.  *    Q3TranslateTransform_Submit(&unitVector, view);
  967.  *    Q3Push_Submit(view);
  968.  *        Q3Attribute_Submit(kQ3AttributeTypeDiffuseColor, &blue, view);
  969.  *        Q3Attribute_Submit(kQ3AttributeTypeTransparencyColor, &green, view);
  970.  *        Q3Box_Submit(&unitBox, view);
  971.  *    Q3Pop_Submit(view);    
  972.  *    Q3TranslateTransform_Submit(&unitVector, view);
  973.  *    Q3Box_Submit(&unitBox, view);
  974.  *    
  975.  *    or by submitting a display group which pushes and pops.
  976.  *    
  977.  *    If you support RendererPush and RendererPop in your renderer:
  978.  *        - you must maintain your drawing state as a stack, as well.
  979.  *        - you will not be updated with the popped state after
  980.  *            RendererPop is called.
  981.  *
  982.  *    If you do not support Push and Pop in your renderer:
  983.  *        - you may maintain a single copy of the drawing state.
  984.  *        - you will be updated with changed fields after the view stack is
  985.  *            popped.
  986.  *
  987.  *    A renderer that supports Push and Pop gets called in the following
  988.  *    sequence (from example above):
  989.  *    
  990.  *    RendererUpdateAttributeDiffuseColor(&red,...)
  991.  *    RendererUpdateAttributeTransparencyColor(&blue,...)
  992.  *    RendererUpdateAttributeSpecularColor(&white,...)
  993.  *    RendererUpdateMatrixLocalToWorld(...)
  994.  *    RendererSubmitGeometryBox(...)
  995.  *    RendererPush(...)
  996.  *        RendererUpdateAttributeDiffuseColor(&blue,...)
  997.  *        RendererUpdateAttributeTransparencyColor(&green,...)
  998.  *        RendererSubmitGeometryBox(...)
  999.  *    RendererPop(...)
  1000.  *    RendererUpdateMatrixLocalToWorld(...)
  1001.  *    RendererSubmitGeometryBox(...)
  1002.  *
  1003.  *    A renderer that does not supports Push and Pop gets called in the
  1004.  *    following sequence:
  1005.  *    
  1006.  *    RendererUpdateAttributeDiffuseColor(&red,...)
  1007.  *    RendererUpdateAttributeTransparencyColor(&blue,...)
  1008.  *    RendererUpdateAttributeSpecularColor(&white,...)
  1009.  *    RendererUpdateMatrixLocalToWorld(...)
  1010.  *    RendererSubmitGeometryBox(...)
  1011.  *        RendererUpdateAttributeDiffuseColor(&blue,...)
  1012.  *        RendererUpdateAttributeTransparencyColor(&green,...)
  1013.  *        RendererSubmitGeometryBox(...)
  1014.  *    RendererUpdateAttributeDiffuseColor(&red,...)
  1015.  *    RendererUpdateAttributeTransparencyColor(&blue,...)
  1016.  *    RendererUpdateMatrixLocalToWorld(...)
  1017.  *    RendererSubmitGeometryBox(...)
  1018.  *    
  1019.  */
  1020.  
  1021. enum {
  1022.     kQ3XMethodTypeRendererPush    = FOUR_CHAR_CODE('rdps')
  1023. };
  1024.  
  1025. typedef CALLBACK_API_C( TQ3Status , TQ3XRendererPushMethod )(TQ3ViewObject view, void *rendererPrivate);
  1026.  
  1027. enum {
  1028.     kQ3XMethodTypeRendererPop    = FOUR_CHAR_CODE('rdpo')
  1029. };
  1030.  
  1031. typedef CALLBACK_API_C( TQ3Status , TQ3XRendererPopMethod )(TQ3ViewObject view, void *rendererPrivate);
  1032. /******************************************************************************
  1033.  **                                                                             **
  1034.  **                            Renderer Cull Methods                             **
  1035.  **                                                                             **
  1036.  *****************************************************************************/
  1037. /*
  1038.  *    kQ3XMethodTypeRendererIsBoundingBoxVisible
  1039.  *    TQ3XRendererIsBoundingBoxVisibleMethod
  1040.  *    
  1041.  *    This method is called to cull complex groups and geometries 
  1042.  *    given their bounding box in local space.
  1043.  *    
  1044.  *    It should transform the local-space bounding box coordinates to
  1045.  *    frustum space and return a TQ3Boolean return value indicating
  1046.  *    whether the box appears within the viewing frustum.
  1047.  *    
  1048.  *    If no method is supplied, the default behavior is to return
  1049.  *    kQ3True.
  1050.  *    
  1051.  */
  1052.  
  1053. enum {
  1054.     kQ3XMethodTypeRendererIsBoundingBoxVisible = FOUR_CHAR_CODE('rdbx')
  1055. };
  1056.  
  1057. typedef CALLBACK_API_C( TQ3Boolean , TQ3XRendererIsBoundingBoxVisibleMethod )(TQ3ViewObject view, void *rendererPrivate, const TQ3BoundingBox *bBox);
  1058.  
  1059. /******************************************************************************
  1060.  **                                                                             **
  1061.  **                        Renderer Object Support Methods                         **
  1062.  **                                                                             **
  1063.  *****************************************************************************/
  1064. /*
  1065.  *    Drawing methods (Geometry, Camera, Lights)
  1066.  *
  1067.  */
  1068. /*
  1069.  *    Geometry MetaHandler
  1070.  *    
  1071.  *    This metaHandler is required to support 
  1072.  *    
  1073.  *    kQ3GeometryTypeTriangle
  1074.  *    kQ3GeometryTypeLine
  1075.  *    kQ3GeometryTypePoint
  1076.  *    kQ3GeometryTypeMarker
  1077.  *    kQ3GeometryTypePixmapMarker
  1078.  *    
  1079.  *    REQUIRED
  1080.  */
  1081.  
  1082. enum {
  1083.     kQ3XMethodTypeRendererSubmitGeometryMetaHandler = FOUR_CHAR_CODE('rdgm')
  1084. };
  1085.  
  1086. typedef CALLBACK_API_C( TQ3XFunctionPointer , TQ3XRendererSubmitGeometryMetaHandlerMethod )(TQ3ObjectType geometryType);
  1087. /*
  1088.  *    The TQ3XRendererSubmitGeometryMetaHandlerMethod switches on geometryType
  1089.  *    of kQ3GeometryTypeFoo and returns methods of type:
  1090.  */
  1091. typedef CALLBACK_API_C( TQ3Status , TQ3XRendererSubmitGeometryMethod )(TQ3ViewObject view, void *rendererPrivate, TQ3GeometryObject geometry, const void *publicData);
  1092. /*
  1093.  *    Camera MetaHandler
  1094.  *    
  1095.  *    This metaHandler, if supplied, indicates that your renderer
  1096.  *    handles deferred transformation of the main camera within a scene.
  1097.  *    
  1098.  *    If not supplied, or an unsupported camera is used, the view will do
  1099.  *    the transformation for the renderer and pass in a camera in the 
  1100.  *    StartPass method.
  1101.  *    
  1102.  *    OPTIONAL
  1103.  */
  1104.  
  1105. enum {
  1106.     kQ3XMethodTypeRendererSubmitCameraMetaHandler = FOUR_CHAR_CODE('rdcm')
  1107. };
  1108.  
  1109. typedef CALLBACK_API_C( TQ3XFunctionPointer , TQ3XRendererSubmitCameraMetaHandlerMethod )(TQ3ObjectType cameraType);
  1110. /*
  1111.  *    The TQ3XRendererSubmitCameraMetaHandlerMethod switches on cameraType
  1112.  *    of kQ3CameraTypeFoo and returns methods of type:
  1113.  */
  1114. typedef CALLBACK_API_C( TQ3Status , TQ3XRendererSubmitCameraMethod )(TQ3ViewObject view, void *rendererPrivate, TQ3CameraObject camera, const void *publicData);
  1115. /*
  1116.  *    Light MetaHandler
  1117.  *    
  1118.  *    This metaHandler, if supplied, indicates that your renderer
  1119.  *    handles deferred transformation of lights within a scene.
  1120.  *    
  1121.  *    If an unsupported light is encountered, it is ignored.
  1122.  *
  1123.  *    OPTIONAL
  1124.  */
  1125.  
  1126. enum {
  1127.     kQ3XMethodTypeRendererSubmitLightMetaHandler = FOUR_CHAR_CODE('rdlg')
  1128. };
  1129.  
  1130. typedef CALLBACK_API_C( TQ3XFunctionPointer , TQ3XRendererSubmitLightMetaHandlerMethod )(TQ3ObjectType lightType);
  1131. /*
  1132.  *    The TQ3XRendererSubmitLightMetaHandlerMethod switches on lightType
  1133.  *    of kQ3LightTypeFoo and returns methods of type:
  1134.  */
  1135. typedef CALLBACK_API_C( TQ3Status , TQ3XRendererSubmitLightMethod )(TQ3ViewObject view, void *rendererPrivate, TQ3LightObject light, const void *publicData);
  1136. /*
  1137.  *
  1138.  *    Update methods
  1139.  *
  1140.  *    They are called whenever the state has changed. If the renderer supports
  1141.  *    the RendererPush and RendererPop methods, it must maintain its own state
  1142.  *    stack. Updates are not called for changed data when the view stack is
  1143.  *    popped.
  1144.  *
  1145.  *    See the comments for the RendererPush and RendererPop methods above
  1146.  *    for an example of how data is updated.
  1147.  *
  1148.  */
  1149. /*
  1150.  *    Style
  1151.  */
  1152.  
  1153. enum {
  1154.     kQ3XMethodTypeRendererUpdateStyleMetaHandler = FOUR_CHAR_CODE('rdyu')
  1155. };
  1156.  
  1157. typedef CALLBACK_API_C( TQ3XFunctionPointer , TQ3XRendererUpdateStyleMetaHandlerMethod )(TQ3ObjectType styleType);
  1158. /*
  1159.  *    The TQ3XRendererUpdateStyleMetaHandlerMethod switches on styleType
  1160.  *    of kQ3StyleTypeFoo and returns methods of type:
  1161.  */
  1162. typedef CALLBACK_API_C( TQ3Status , TQ3XRendererUpdateStyleMethod )(TQ3ViewObject view, void *rendererPrivate, const void *publicData);
  1163. /*
  1164.  *    Attributes
  1165.  */
  1166.  
  1167. enum {
  1168.     kQ3XMethodTypeRendererUpdateAttributeMetaHandler = FOUR_CHAR_CODE('rdau')
  1169. };
  1170.  
  1171. typedef CALLBACK_API_C( TQ3XFunctionPointer , TQ3XRendererUpdateAttributeMetaHandlerMethod )(TQ3AttributeType attributeType);
  1172. /*
  1173.  *    The TQ3XRendererUpdateStyleMetaHandlerMethod switches on attributeType
  1174.  *    of kQ3AttributeTypeFoo and returns methods of type:
  1175.  */
  1176. typedef CALLBACK_API_C( TQ3Status , TQ3XRendererUpdateAttributeMethod )(TQ3ViewObject view, void *rendererPrivate, const void *publicData);
  1177. /*
  1178.  *    Shaders
  1179.  */
  1180.  
  1181. enum {
  1182.     kQ3XMethodTypeRendererUpdateShaderMetaHandler = FOUR_CHAR_CODE('rdsu')
  1183. };
  1184.  
  1185. typedef CALLBACK_API_C( TQ3XFunctionPointer , TQ3XRendererUpdateShaderMetaHandlerMethod )(TQ3ObjectType shaderType);
  1186. /*
  1187.  *    The TQ3XRendererUpdateShaderMetaHandlerMethod switches on shaderType
  1188.  *    of kQ3ShaderTypeFoo and returns methods of type:
  1189.  */
  1190. typedef CALLBACK_API_C( TQ3Status , TQ3XRendererUpdateShaderMethod )(TQ3ViewObject view, void *rendererPrivate, TQ3Object *shaderObject);
  1191. /*
  1192.  *    Matrices
  1193.  */
  1194.  
  1195. enum {
  1196.     kQ3XMethodTypeRendererUpdateMatrixMetaHandler = FOUR_CHAR_CODE('rdxu')
  1197. };
  1198.  
  1199. typedef TQ3XMetaHandler                 TQ3XRendererUpdateMatrixMetaHandlerMethod;
  1200. /*
  1201.  *    The TQ3XRendererUpdateShaderMetaHandlerMethod switches on methods
  1202.  *    of the form kQ3MethodTypeRendererUpdateMatrixFoo:
  1203.  */
  1204.  
  1205. enum {
  1206.     kQ3XMethodTypeRendererUpdateMatrixLocalToWorld = FOUR_CHAR_CODE('ulwx')
  1207. };
  1208.  
  1209.  
  1210. enum {
  1211.     kQ3XMethodTypeRendererUpdateMatrixLocalToWorldInverse = FOUR_CHAR_CODE('ulwi')
  1212. };
  1213.  
  1214.  
  1215. enum {
  1216.     kQ3XMethodTypeRendererUpdateMatrixLocalToWorldInverseTranspose = FOUR_CHAR_CODE('ulwt')
  1217. };
  1218.  
  1219.  
  1220. enum {
  1221.     kQ3XMethodTypeRendererUpdateMatrixLocalToCamera = FOUR_CHAR_CODE('ulcx')
  1222. };
  1223.  
  1224.  
  1225. enum {
  1226.     kQ3XMethodTypeRendererUpdateMatrixLocalToFrustum = FOUR_CHAR_CODE('ulfx')
  1227. };
  1228.  
  1229.  
  1230. enum {
  1231.     kQ3XMethodTypeRendererUpdateMatrixWorldToFrustum = FOUR_CHAR_CODE('uwfx')
  1232. };
  1233.  
  1234. /*
  1235.  *    and returns methods of type:
  1236.  */
  1237. typedef CALLBACK_API_C( TQ3Status , TQ3XRendererUpdateMatrixMethod )(TQ3ViewObject view, void *rendererPrivate, const TQ3Matrix4x4 *matrix);
  1238.  
  1239.  
  1240. #if PRAGMA_ENUM_ALWAYSINT
  1241.     #pragma enumsalwaysint reset
  1242. #elif PRAGMA_ENUM_OPTIONS
  1243.     #pragma option enum=reset
  1244. #elif defined(PRAGMA_ENUM_PACK__QD3DRENDERER__)
  1245.     #pragma options(pack_enums)
  1246. #endif
  1247.  
  1248. #if PRAGMA_STRUCT_ALIGN
  1249.     #pragma options align=reset
  1250. #elif PRAGMA_STRUCT_PACKPUSH
  1251.     #pragma pack(pop)
  1252. #elif PRAGMA_STRUCT_PACK
  1253.     #pragma pack()
  1254. #endif
  1255.  
  1256. #ifdef PRAGMA_IMPORT_OFF
  1257. #pragma import off
  1258. #elif PRAGMA_IMPORT
  1259. #pragma import reset
  1260. #endif
  1261.  
  1262. #ifdef __cplusplus
  1263. }
  1264. #endif
  1265.  
  1266. #endif /* __QD3DRENDERER__ */
  1267.  
  1268.